# Проект для анализа кластеризации объектов и маршрутов связи в 3D пространстве

Проект содержит модули и пакеты выполняющие функции:
- Генерация объектов в 3D пространстве или чтение координат из файла для анализа.
- Кластеризация объектов алгоритмом K-Means. 
- Генерация графа сети на основе информации об объектах и кластерах.
- Фильтрация графа сети по количеству каналов между объектами.
- Формирование сета данных и сохранение в файл.
- Печать статистической информации о результатах в терминал.
- Поиск оптимального маршрута алгоритмом Дейкстры.
- Визуализация кластеров, объектов, графов и путей на 3D-графиках.

## Настройка и установка

1. Установить Anaconda и запустить VS Code из панели Anaconda

2. Клонировать репозиторий и открыть директорию с проектом в VS Code

3. Проверить настройки в config.yaml

4. Запустить необходимый сценарии из основной директории проекта.

## Пример работы модуля 

Визуализация маршрутов связи на 3D графике в следующей конфигурации:
- Сет из 100 произвольных объектов
- Кластеризация на 15 кластеров
- 3 канала связи с базовой станцией и 4 канала связи у каждого кластера
- Маршруты для 5 объектов до базовой станции
- Использован скрипт `main.py`

![Визуализация маршрутов связи](./images/paths.png)

## Сценарии и функции

### Генерация объектов в 3D пространстве

Файл `main.py` выполняет последовательный запуск всех модулей и функций.

### Генерация объектов в 3D пространстве

Модуль генерации объектов в 3D пространстве: произвольные точки, сеть, ряды. 

Можно настроить размер пространства, расстояние между точками и диапазон отклонения

Файл `generate_swarm.py`

Результат будет сохранён в файл согласно конфигурации и построен 3D-график:

Пример 100 объектов, 5 рядов и расстоянием 500 между объектами
![Генерация рядов объектов в 3D](./images/objects-rows.png)

Пример произвольных 100 объектов, в квадрате со стороной 5000
![Генерация произвольных объектов в 3D](./images/objects-random.png)

### Кластеризация 

Файл `clustering_data.py`

Модуль кластеризует объекты методом K-Means, определяет центроиды и выделяет ближайший к центроиду объект

Результат будет сохранён в файл согласно конфигурации и построен 3D-график.

![Кластеризация объектов](./images/clusters.png)

### Визуализация сети кластеров без создания графов

Модуль позволяет визуализировать связи и вывести статистику без создания графов

Файл `communication_relations.py`

Пример 3D визуализации:

![Визуализация сети кластеров](./images/clusters-network.png)

### Создание графа сети 

Файлы
- Без фильтрации `network_graph.py`
- Фильтрация по количеству связей `network_graph_filtered.py`

Внутри кластеров создаётся связь между объектами и ближайшим к центроиду главным объектом - Лидером. 

Между кластерами создаётся связь между Лидерами.

Вводится определение базовой станции и связи между лидерами и базовой станцией.

Возможно настроить количество связей лидеров и базовой станции (пример с фильтрацией).

Доступны настройки отображения как параметры функций отображения.

Используется библиотека NetworkX.

Результат без фильтрации
![Визуализация сети кластеров](./images/graph-without-filters.png)

Результат с фильтрацией без отображения объектов
![Визуализация сети кластеров](./images/graph-filtered-no-objects.png)

Результат с фильтрацией с отображением объектов
![Визуализация сети кластеров](./images/graph-filtered-with-objects.png)

### Прокладывание маршрутов сети и визуализация маршрутов

Выполняется поиск оптимального пути связи на основе графов сети. 
В текущей конфигурации это поиск оптимального маршрута от объекта до базовой станциии, через главные объекты в кластерах.

Используется алгоритм Дейкстрый и библиотека NetworkX.

Файл `routing_data_file.py` и `main.py`

Модуль рассчитывает путь и дистанции для всех объектов дата сета. Результаты выводятся в терминал, сохраняются в итоговый CSV файл и визуализируются на 3D графике для выбранных объектов.

Пример 3D графика с выбором 5 объектов

![Визуализация маршрутов связи](./images/paths.png)

### Формирование дата сета и статистических данных для анализа

Если визуализация не требуется, а модуль используется только для формирования дата сета и получения данных для аналитики. 

Файл `statistic_data.py`

Скрипт выполнит все функции и сохранит результаты в файл и выведет результаты в терминал.

## Примеры использования

Модуль создан для анализа результатов маршрутизации и кластеризации. 

Результаты работы скриптов сохраняются в файлы в формате CSV, для дальнейшего анализа или использования.

Примеры датасетов доступны в папке `data`, например файл `data-objects-random-5000-100-1000-results-objects.csv`.

Например, итоговый датасет объектов имеет поля:
- object_id, name, x,y,z  - Информация об объектах
- cluster_id, distance_to_centroid - Информация о кластере
- leader - является ли объект главным в кластере
- leader_id, leader_x, leader_y, leader_z - Информация о главном в кластере объекта
- distance_to_leader, distance_to_base - дистанции до главного в кластере и базовой станции
- base_connector - является ли объект связующим с базовой станцией
- shortest_path - маршрут связи до базовой станции
- shortest_path_length - дистанция маршрута
- shortest_path_steps - количество шагов
- shortest_path_steps_length - длина каждого шага
- shortest_path_usage_count - количество использований в маршрутах

## Пример вывода статистики в терминал

### Статистика по объектам и кластерам

Функция `clusters.print_stat(df)`

```
Итоговое количество кластеров: 15

Количество объектов в кластерах: 9, 11, 6, 8, 5, 6, 9, 10, 6, 4, 4, 3, 8, 6, 5

Количество объектов: 100

Данные по дистанциям:
        Расстояние до базовой станции  Маршрут до базовой станции  Расстояние до лидера  Шагов в маршруте
min                       1146.943700                   1346.8600             82.343503          1.000000
mean                      3983.010359                   4719.0466            452.482864          2.670588
median                    4312.720030                   5111.9400            447.334112          3.000000
max                       6922.874804                   7673.6100            919.405928          4.000000

Среднее количество шагов в маршрутах связи: 2.67

Распределение по количеству шагов в маршруте:

   Количество шагов  Количество объектов
0                 3                   31
1                 2                   20
2                 4                   20
3                 1                   14

    ID лидера  ID кластера  Количество использований
35         36            2                        51
51         52           13                        42
68         69            3                        27
23         24            9                        22
24         25           11                        22
25         26            5                        19
6           7            4                        13
91         92            1                        10
46         47            7                         9
5           6            0                         8
67         68            6                         8
36         37           12                         7
20         21            8                         5
28         29           14                         4
93         94           10                         3
```

### Статистика по графам сети

Функция `graph.print_stat(Graph)`

```
Итоговое количество кластеров: 15

Количество объектов в кластерах: 9, 11, 6, 8, 5, 6, 9, 10, 6, 4, 4, 3, 8, 6, 5

Общее количество нод: 101, рёбер: 126, связей: 252

Статистика по группам рёбер графа:

     Группа ребёр  Количество ребёр      Минимум     Максимум      Медиана      Среднее
0  base_connector                 3  1346.855339  2046.590318  1446.707738  1613.384465
1         leaders                38   619.905569  2544.423507  1490.102791  1541.835367
2          object                85    82.343503   919.405928   447.334112   452.482864
3      Все группы               126    82.343503  2544.423507   564.985942   808.658260

Статистика по группам нод графа:

  Группа нод  Количество нод
0       base               1
1     leader              15
2     object              85

Общее количество связей: 252

   Количество связей  Количество нод
0                  1              85
1                 12               4
2                 10               3
3                 13               3
4                  9               2
5                  7               2
6                 15               1
7                  3               1
```
